home *** CD-ROM | disk | FTP | other *** search
/ Aminet 40 / Aminet 40 (2000)(Schatztruhe)[!][Dec 2000].iso / Aminet / mus / misc / MPEG_S_LAMEppc.lha / mpeg_s_LAME3.87 / STYLEGUIDE < prev    next >
Text File  |  1980-09-26  |  7KB  |  174 lines
  1. * The LAME API is frozen.  Poorly designed as it is, dont change it, 
  2.   and add to it sparingly.
  3.  
  4. * Dont take it upon yourself to go through LAME with the sole purpose
  5.   of updating everything to match this guide.  Especially important:
  6.   dont change the spacing, indentation, curly braces, etc, 
  7.   in routines you did not write.
  8.  
  9. * Respect the indentation of the author of the original function.
  10.   If the indentation is not consistent, use 3.
  11.  
  12. * Don't use tabulators (the character with the value '\t') in source code,
  13.   especially these with a width of unequal 8. Lame sources are using
  14.   different sizes for tabulators.
  15.  
  16. * Don't set the macro NDEBUG in alpha versons.
  17.   NDEBUG should be set for beta versions.
  18.  
  19. * check important assumptions with an assert()
  20.  
  21. * use int for all integer quantities if possible.  
  22.   LAME requires 32 bit ints, so you can assume int is at least 32 bits.  
  23.   Dont use 'long'.  Dont use 'unsigned' unless absolutely necessary.
  24.   If 64 bits is required, use int64.
  25.  
  26. * Avoid using float or double, and instead use: (defined in machine.h).  
  27.  
  28. FLOAT    for variables which require at least 32bits
  29. FLOAT8   for variables which require at least 64bits
  30.  
  31. On some machines, 64bit will be faster than 32bit.  Also, some math
  32. routines require 64bit float, so setting FLOAT=float will result in a
  33. lot of conversions.
  34.  
  35. * The internal representation of PCM samples in type 'sample_t',
  36.   currently this is a FLOAT.  
  37.  
  38. * Use the 'const' attribute if you don't intend to change the variable.
  39.  
  40. * Use SI base units. Lame mixes Hz, kHz, kbps, bps. This is mess.
  41.  
  42.   Example:
  43.         float     wavelength_green = 555.e-9;
  44.         unsigned  data_rate        = 128000;
  45.         float     lowpass_freq     = 12500.;
  46.   
  47.   Converting between user input and internal representation should be done
  48.   near the user interface, not in the most inner loop of an utility
  49.   function.
  50.  
  51. ----------------------------------------------------------------------------------
  52. Edited version of the Linux Kernel Style Guide:
  53. ----------------------------------------------------------------------------------
  54.  
  55.                 Chapter 1: Indentation
  56.  
  57. Respect the indentation of the author of the original function.
  58. If the indentation is not consistent, dont change it.  If
  59. you are so anal-retentive about these things and you cant
  60. bare to even look at code with poor indentation, change it to 3.
  61.  
  62.  
  63.                 Chapter 2: Placing Braces
  64.  
  65. The other issue that always comes up in C styling is the placement of
  66. braces.  Unlike the indent size, there are few technical reasons to
  67. choose one placement strategy over the other, but the preferred way, as
  68. shown to us by the prophets Kernighan and Ritchie, is to put the opening
  69. brace last on the line, and put the closing brace first, thusly:
  70.  
  71.         if (x is true) {
  72.                 we do y
  73.         }
  74.  
  75. However, there is one special case, namely functions: they have the
  76. opening brace at the beginning of the next line, thus:
  77.  
  78.         int function(int x)
  79.         {
  80.                 body of function
  81.         }
  82.  
  83. Heretic people all over the world have claimed that this inconsistency
  84. is ...  well ...  inconsistent, but all right-thinking people know that
  85. (a) K&R are _right_ and (b) K&R are right.  Besides, functions are
  86. special anyway (you can't nest them in C). 
  87.  
  88. Note that the closing brace is empty on a line of its own, _except_ in
  89. the cases where it is followed by a continuation of the same statement,
  90. ie a "while" in a do-statement or an "else" in an if-statement, like
  91. this:
  92.  
  93.         do {
  94.                 body of do-loop
  95.         } while (condition);
  96.  
  97. and
  98.  
  99.         if (x == y) {
  100.                 ..
  101.         } else if (x > y) {
  102.                 ...
  103.         } else {
  104.                 ....
  105.         }
  106.                         
  107. Rationale: K&R. 
  108.  
  109. Also, note that this brace-placement also minimizes the number of empty
  110. (or almost empty) lines, without any loss of readability.  Thus, as the
  111. supply of new-lines on your screen is not a renewable resource (think
  112. 25-line terminal screens here), you have more empty lines to put
  113. comments on. 
  114.  
  115.  
  116.                 Chapter 3: Naming
  117.  
  118. C is a Spartan language, and so should your naming be.  Unlike Modula-2
  119. and Pascal programmers, C programmers do not use cute names like
  120. ThisVariableIsATemporaryCounter.  A C programmer would call that
  121. variable "tmp", which is much easier to write, and not the least more
  122. difficult to understand. 
  123.  
  124. HOWEVER, while mixed-case names are frowned upon, descriptive names for
  125. global variables are a must.  To call a global function "foo" is a
  126. shooting offense. 
  127.  
  128. GLOBAL variables (to be used only if you _really_ need them) need to
  129. have descriptive names, as do global functions.  If you have a function
  130. that counts the number of active users, you should call that
  131. "count_active_users()" or similar, you should _not_ call it "cntusr()". 
  132.  
  133. Encoding the type of a function into the name (so-called Hungarian
  134. notation) is brain damaged - the compiler knows the types anyway and can
  135. check those, and it only confuses the programmer.  No wonder MicroSoft
  136. makes buggy programs. 
  137.  
  138. LOCAL variable names should be short, and to the point.  If you have
  139. some random integer loop counter, it should probably be called "i". 
  140. Calling it "loop_counter" is non-productive, if there is no chance of it
  141. being mis-understood.  Similarly, "tmp" can be just about any type of
  142. variable that is used to hold a temporary value. 
  143.  
  144.  
  145.                 
  146.                 Chapter 4: Functions
  147.  
  148. Document functions.  
  149.  
  150. Keep functions as modular as possible.  But dont adhere to artificial
  151. line number limitations.  For example, lame_encode_frame() encodes a
  152. single MP3 frame and is a long sequence of function calls.  It makes
  153. no sense to break this into two or more routines.
  154.  
  155.  
  156.  
  157.                 Chapter 5: Commenting
  158.  
  159. Comments are good, but there is also a danger of over-commenting.  NEVER
  160. try to explain HOW your code works in a comment: it's much better to
  161. write the code so that the _working_ is obvious, and it's a waste of
  162. time to explain badly written code. 
  163.  
  164. Generally, you want your comments to tell WHAT your code does, not HOW. 
  165. Also, try to avoid putting comments inside a function body: if the
  166. function is so complex that you need to separately comment parts of it,
  167. you should probably go back to chapter 4 for a while.  You can make
  168. small comments to note or warn about something particularly clever (or
  169. ugly), but try to avoid excess.  Instead, put the comments at the head
  170. of the function, telling people what it does, and possibly WHY it does
  171. it. 
  172.  
  173.  
  174.